Add codespell: config + action (to detect new typos) and make it fix a good number of them #11195

yarikoptic · 2024-03-07T23:19:41Z

codespell was used occasionally on some files, so not a new tool here. But now it would guard RTD from having typos introduced to begin with.

Note that some fixes could affect (fix) functionality.

There is an odd "variable" syntaxt which I didn't fix since seems would require transition and smells like it is on purpose:

❯ git grep syntaxt -- readthedocs/
readthedocs/projects/migrations/0106_add_addons_config.py:                ("syntaxt", models.CharField(max_length=128)),
readthedocs/projects/models.py:    syntaxt = models.CharField(max_length=128)
readthedocs/projects/tasks/builds.py:        grab them by using glob syntaxt between other files that could be garbage.

or was it intended to be syntax ?

TODOs

Remove TEMP commit intended to test if pre-commit catches the added malicious typo
Final decision on fixing or not CHANGELOG.rst
Pre-commit configuration for codespell common#212 needs to be merged first

📚 Documentation previews 📚

User's documentation (docs): https://docs--11195.org.readthedocs.build/en/11195/

Developer's documentation (dev): https://dev--11195.org.readthedocs.build/en/11195/

sentry-io · 2024-03-07T23:19:52Z

🔍 Existing Issues For Review

Your pull request is modifying functions with the following pre-existing issues:

📄 File: readthedocs/api/v2/views/integrations.py

Function	Unhandled Issue
`get_closed_external_version_response`	TypeError: 'NoneType' object is not subscriptable /api/v2/webhook/{project_slug}/{integration_pk}... `Event Count:` 1

_{Did you find this useful? React with a 👍 or 👎}

humitos

Thanks for the PR 👍🏼

I didn't take a full review, but I noted a few issues that I see will generate some conflicts. In particular, those that change Python code and require some manual interaction (e.g. a Django migration to update the help_text)

I'm not opposed to this work, but I find it hard to prioritize by the core team at this point.

readthedocs/builds/migrations/0007_add-automation-rules.py

CHANGELOG.rst

.github/workflows/codespell.yml

agjohnson · 2024-03-08T18:56:06Z

We use pre-commit for all other linting checks. I feel if we implement this it should be at pre-commit, not GHA.

yarikoptic · 2024-03-08T21:57:57Z

Hmm, interesting, my script should've detected presence of pre-commit config... Will have a look wherever get a chance. You do have ci job running the pre-commit I assume? (I don't see report from pre-commit service)

yarikoptic · 2024-03-08T22:11:04Z

that explains it:

❯ ls -ld .pre-commit-config.yaml
lrwxrwxrwx 1 yoh yoh 29 Mar  7 18:00 .pre-commit-config.yaml -> common/pre-commit-config.yaml
❯ cat .pre-commit-config.yaml
cat: .pre-commit-config.yaml: No such file or directory
❯ git submodule
-4af0fffd2cbeeb40f0a71b875beb99d6dc88a355 common

Let's do the submodules dance now...

Ref: readthedocs/readthedocs.org#11195

humitos · 2025-07-24T12:44:50Z

This PR is great! Thanks for opening it!

I'd like to move forward with it. I've already reviewed readthedocs/common#212

We need to make some adjustments here and we can move forward 👍🏼 . @yarikoptic are you able to continue with this work?

Final decision on fixing or not CHANGELOG.rst

Let's exclude the changelog for now. It has a lot of noise.

let me exclude all such lines with help_text *=.*

We should implement this, if it's not already.

yarikoptic · 2025-07-24T14:47:44Z

We need to make some adjustments here and we can move forward 👍🏼 . @yarikoptic are you able to continue with this work?

I am able as soon as there is cycles on your end so PR doesn't amass conflicts to address again.

Per readthedocs#11195 (comment)

read-the-docs-community · 2025-07-24T15:13:30Z

Documentation build overview

📚 dev | 🛠️ build #28967931 (c5202bd) | 🔍 preview

Files changed

Comparing with latest (000af14...c5202bd)

Show files (5) | 5 modified | 0 added | 0 deleted

File	Status
aws-temporary-credentials.html	📝 modified
github-app.html	📝 modified
design/build-images.html	📝 modified
design/future-builder.html	📝 modified
design/new-search-api.html	📝 modified

read-the-docs-community · 2025-07-24T15:13:43Z

Documentation build overview

📚 docs | 🛠️ build #28967932 (c5202bd) | 🔍 preview

Files changed

Comparing with latest (000af14...c5202bd)

Show files (1) | 1 modified | 0 added | 0 deleted

File	Status
guides/creating-project-private-repository.html	📝 modified

yarikoptic · 2025-07-24T15:14:23Z

FWIW, I have rebased and redone codespell fixing (automated and interactive). Let's see if no side effects. Please review the diff.

humitos

This is great! I suppose there may be a few test failing because there are some words that shouldn't return search results.

readthedocs/config/notifications.py

humitos · 2025-07-24T15:21:52Z

readthedocs/search/tests/test_api.py

@@ -526,7 +526,7 @@ def test_search_advanced_query_detection(self, api_client):
        search_params = {
            "project": project.slug,
            "version": version.slug,
-            "q": "indx",
+            "q": "index",


This was probably an invalid word on purpose.

so we need to annotate this line to be skipped and ok to contain indx?

I replaced it with explicit "abracadabra" , or it does have to be "indx"? (let's see if tests feel better)

The test is failing. I think it needs to be indx probably for fuzzy search testing. I would leave as it was to avoid this type of issues and probably mark that line to be skipped 👍🏼

…nteractively === Do not change lines below === { "chain": [], "cmd": "codespell -w -i 3 -C 4", "exit": 0, "extra_inputs": [], "inputs": [], "outputs": [], "pwd": "." } ^^^ Do not change lines above ^^^

… 'abracadabra'

…os automagically === Do not change lines below === { "chain": [], "cmd": "codespell -w", "exit": 0, "extra_inputs": [], "inputs": [], "outputs": [], "pwd": "." } ^^^ Do not change lines above ^^^

Ref: readthedocs/readthedocs.org#11195

humitos · 2025-07-25T12:01:16Z

There is an odd "variable" syntaxt which I didn't fix since seems would require transition and smells like it is on purpose:

This is indeed a typo that I made when I created the model's field AddonSearchFilter.syntaxt, yes 😓 . Let's leave as-is for now because it will require a migration. We can do this in a different PR. It should be easy since this field it's not being used yet.

humitos · 2025-07-25T12:05:14Z

setup.cfg

+[codespell]
+# Ref: https://github.com/codespell-project/codespell#using-a-config-file
+skip = .git,*.svg,locale,package-lock.json,*.css,*.min.*,vendor,*.ai,setup.cfg,migrations,CHANGELOG.rst,common
+check-hidden = true
+# some names and abbreviations and very long lines (minimized?)
+# TODO: fixup help_text in readthedocs/builds/models.py : "to perfom an"
+ignore-regex = \b(Manuel|DED|Wile E. Coyote|Couldn\\u2019t|to perfom an)\b|.{300,}|"pyton\b|\|(ative|ment)\||"Hel" will match\b|ative: ''|help_text *=.*
+# TODO: fix syntaxt -- would require transition?
+ignore-words-list = fo,te,astroid,requestor,syntaxt,ore


Is it possible to put all this configuration on a specific codespell file? Like .codespell.cfg or similar?

We will need to put this file into common/ repository (readthedocs/common#212) because we want to share this configuration across multiple repositories, eg. https://github.com/readthedocs/ext-theme

It seems .codespellrc https://github.com/codespell-project/codespell#using-a-config-file

We want that file to be in common/ and symlinked from here 👍🏼

yarikoptic requested review from a team as code owners March 7, 2024 23:19

yarikoptic requested review from ericholscher and agjohnson March 7, 2024 23:19

auto-assign bot assigned yarikoptic Mar 7, 2024

humitos reviewed Mar 8, 2024

View reviewed changes

readthedocs/builds/migrations/0007_add-automation-rules.py Outdated Show resolved Hide resolved

CHANGELOG.rst Outdated Show resolved Hide resolved

.github/workflows/codespell.yml Outdated Show resolved Hide resolved

.github/workflows/codespell.yml Outdated Show resolved Hide resolved

yarikoptic added a commit to yarikoptic/common that referenced this pull request Mar 8, 2024

Add codespell to pre-commit

ab757de

Ref: readthedocs/readthedocs.org#11195

yarikoptic mentioned this pull request Mar 8, 2024

Pre-commit configuration for codespell readthedocs/common#212

Open

yarikoptic force-pushed the enh-codespell branch from 51b4bb1 to ef04ef4 Compare March 8, 2024 23:04

yarikoptic marked this pull request as draft March 8, 2024 23:05

yarikoptic force-pushed the enh-codespell branch from ef04ef4 to 120e693 Compare March 8, 2024 23:16

humitos mentioned this pull request Mar 9, 2024

Blog post: How do use vale with RTD readthedocs/website#274

Open

cclauss mentioned this pull request Oct 12, 2024

codespell the docs directory #11664

Merged

yarikoptic added 7 commits July 24, 2025 10:50

Add codespell config to setup.cfg

929d3ab

Add leftover skips for codespell

2c09eda

Do not codespell migrations

1861f9f

Ignore "to perfom an" for now

14639d1

Exclude CHANGELOG.rst and help_text files

a7fa169

Per readthedocs#11195 (comment)

Ignore common/ from codespell

5ae09d0

Ignore "ore" which seems to be used in examples etc

d9599d4

yarikoptic force-pushed the enh-codespell branch from 120e693 to 40091fd Compare July 24, 2025 15:12

humitos reviewed Jul 24, 2025

View reviewed changes

yarikoptic added 3 commits July 24, 2025 11:54

[DATALAD RUNCMD] chore: run codespell throughout fixing a few typos i…

5a5a5f6

…nteractively === Do not change lines below === { "chain": [], "cmd": "codespell -w -i 3 -C 4", "exit": 0, "extra_inputs": [], "inputs": [], "outputs": [], "pwd": "." } ^^^ Do not change lines above ^^^

Replace 'indx' in search query within test to explicitly non-matching…

28527bf

… 'abracadabra'

[DATALAD RUNCMD] chore: run codespell throughout fixing a few new typ…

c5202bd

…os automagically === Do not change lines below === { "chain": [], "cmd": "codespell -w", "exit": 0, "extra_inputs": [], "inputs": [], "outputs": [], "pwd": "." } ^^^ Do not change lines above ^^^

yarikoptic force-pushed the enh-codespell branch from 40091fd to c5202bd Compare July 24, 2025 15:56

yarikoptic added a commit to yarikoptic/common that referenced this pull request Jul 24, 2025

Add codespell to pre-commit

89e3662

Ref: readthedocs/readthedocs.org#11195

humitos reviewed Jul 25, 2025

View reviewed changes

Uh oh!

Add codespell: config + action (to detect new typos) and make it fix a good number of them #11195

Are you sure you want to change the base?

Add codespell: config + action (to detect new typos) and make it fix a good number of them #11195

Uh oh!

Conversation

yarikoptic commented Mar 7, 2024 • edited by humitos Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

sentry-io bot commented Mar 7, 2024

🔍 Existing Issues For Review

Uh oh!

humitos left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

agjohnson commented Mar 8, 2024

Uh oh!

yarikoptic commented Mar 8, 2024

Uh oh!

yarikoptic commented Mar 8, 2024

Uh oh!

humitos commented Jul 24, 2025

Uh oh!

yarikoptic commented Jul 24, 2025

Uh oh!

read-the-docs-community bot commented Jul 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Documentation build overview

Files changed

Uh oh!

read-the-docs-community bot commented Jul 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Documentation build overview

Files changed

Uh oh!

yarikoptic commented Jul 24, 2025

Uh oh!

humitos left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

humitos Jul 24, 2025

Choose a reason for hiding this comment

Uh oh!

yarikoptic Jul 24, 2025

Choose a reason for hiding this comment

Uh oh!

yarikoptic Jul 24, 2025

Choose a reason for hiding this comment

Uh oh!

humitos Jul 25, 2025

Choose a reason for hiding this comment

Uh oh!

humitos commented Jul 25, 2025

Uh oh!

humitos Jul 25, 2025

Choose a reason for hiding this comment

Uh oh!

humitos Jul 25, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

yarikoptic commented Mar 7, 2024 •

edited by humitos

Loading

read-the-docs-community bot commented Jul 24, 2025 •

edited

Loading

read-the-docs-community bot commented Jul 24, 2025 •

edited

Loading